Skip to main content

Sub-Phase 1.0: Repo & Type Lock

Encode the Phase 0 unified response into types so that schema drift becomes impossible by accident.

Objective​

If someone wants to change meaning later, they must edit Phase 0 first.

Exit Criteria​

  • Types compile
  • No implementation logic exists
  • Schema matches Phase 0 exactly

Project Structure​

scoreSDK/
├── src/
│   └── types/
│       ├── index.ts          # Re-exports all types
│       ├── unified.ts        # UnifiedProfile root type
│       ├── identity.ts       # Identity type
│       ├── availability.ts   # Availability states
│       ├── ethos.ts          # Ethos facet types
│       ├── talent.ts         # Talent facet types
│       └── config.ts         # SDK configuration types
├── package.json
├── tsconfig.json
└── .gitignore

TypeScript Types​

Availability States​

export type AvailabilityState =
  | "available" // profile exists and data fetched
  | "not_found" // no profile exists
  | "unlinked" // identity exists but is not linked
  | "error"; // API error or failure

export interface Availability {
  ethos: AvailabilityState;
  talent: AvailabilityState;
}

Ethos Facet​

export interface EthosFacet {
  data: {
    score: number;
    vouchesReceived: number;
    reviews: {
      positive: number;
      neutral: number;
      negative: number;
    };
  };
  signals: {
    hasNegativeReviews: boolean;
    hasVouches: boolean;
  };
  meta: {
    firstSeenAt: string | null;
    lastUpdatedAt: string | null;
    activeSinceDays: number | null;
  };
}

FORBIDDEN fields: influenceFactor, XP, percentile, ranking

Talent Facet​

export interface TalentFacet {
  data: {
    builderScore: number;
  };
  signals: {
    verifiedBuilder: boolean;
  };
  meta: {
    lastUpdatedAt: string | null;
  };
}

FORBIDDEN fields: ranking, scorer variants

UnifiedProfile​

export interface UnifiedProfile {
  identity: Identity;
  availability: Availability;
  ethos?: EthosFacet; // Present only when available
  talent?: TalentFacet; // Present only when available
}

Architecture​

Public API (getUnifiedProfile)
       ↓
Use Case / Business Logic (unified assembly)
       ↓
Repository (Ethos + Talent adapters)
       ↓
External API (Ethos API, Talent Protocol API)

Exit Checklist​

  • Types compile (npm run typecheck passes)
  • No network code exists
  • No adapter logic exists
  • Unified schema matches Phase 0 exactly
  • No "future" fields sneaked in